<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>bmqa_messageeventbuilder Component</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="bdedox.css" rel="stylesheet" type="text/css"/>
    <style>
      div.hanging {
        padding-left: 0.75in;
        text-indent: -0.50in;
      }
      div.unhanging {
        text-indent:     0in;
      }
      a.glossary {
        font-weight: bold;
        font-style: italic;
      }
    </style>
</head>
<!--
<body onload='searchBox.OnSelectItem(0);'>
-->
<body>

<table border=2 cellspacing=0 cellpadding=0 align=center>
<tr>
 <td valign=top align=center>
 <p align=center><b><i>Quick Links:</i></b></p>
 </td>
 <td valign=top align=center>
 <p align=center>
<a class="qindex" href="group__bmqa.html" target="_blank">bmqa</a> | <a class="qindex" href="group__bmqpi.html" target="_blank">bmqpi</a> | <a class="qindex" href="group__bmqt.html" target="_blank">bmqt</a>
 </td>
 </tr>
 </table>

  </div>
<!-- Generated by Doxygen 1.7.1 -->
<div class="navigation" id="top">
  <div class="tabs">
    <ul class="tablist">
      <li><a href="components.html"><span>Main&nbsp;Page</span></a></li>
      <li><a href="components.html"><span>Components</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div class="header">
  <div class="summary">
<a href="#namespaces">Namespaces</a>  </div>
  <div class="headertitle">
<h1>Component bmqa_messageeventbuilder<br/>
<small>
[<a class="el" href="group__bmqa.html">Package bmqa</a>]</small>
</h1>  </div>
</div>
<div class="contents">

<p>Provide a builder for <code>MessageEvent</code> objects.  
<a href="#_details">More...</a></p>
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="namespaces"></a>
Namespaces</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">namespace &nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespacebmqa.html">bmqa</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">namespace &nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespacebmqp.html">bmqp</a></td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<dl class="user"><dt><b>Outline</b></dt><dd><ul>
<li>
<a href="#1">Purpose</a> </li>
<li>
<a href="#2">Classes</a> </li>
<li>
<a href="#3">Description</a> <ul>
<li>
<a href="#3.1">Usage</a> </li>
<li>
<a href="#3.2">Example 1 - Basic Usage</a> </li>
<li>
<a href="#3.3">Example 2 - Packing multiple messages in a message event</a> </li>
<li>
<a href="#3.4">Thread Safety</a> </li>
</ul>
</li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="purpose"></a> <a class="anchor" id="1"></a> </dd></dl>
<dl class="user"><dt><b>Purpose: </b></dt><dd>Provide a builder for <code>MessageEvent</code> objects. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="classes"></a> <a class="anchor" id="2"></a> </dd></dl>
<dl class="user"><dt><b>Classes: </b></dt><dd><table class="doxtable">
<tr>
<td><a class="el" href="classbmqa_1_1MessageEventBuilder.html">bmqa::MessageEventBuilder</a> </td><td>a builder for <code>MessageEvent</code>.  </td></tr>
</table>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="description"></a> <a class="anchor" id="3"></a> </dd></dl>
<dl class="user"><dt><b>Description: </b></dt><dd>This component implements a mechanism, <code><a class="el" href="classbmqa_1_1MessageEventBuilder.html">bmqa::MessageEventBuilder</a></code>, that can be used for creating message events containing one or multiple messages. The resulting MessageEvent can be sent to the BlazingMQ broker using the <code><a class="el" href="classbmqa_1_1Session.html">bmqa::Session</a></code> (refer to <code>bmqa_session</code> for details). </dd></dl>
<dl class="user"><dt><b></b></dt><dd>The builder holds a <code>MessageEvent</code> under construction, and provides methods to return a reference to the current message (in order to set its various members), as well as to append a new message. Once the application is done, the builder provides a method to get the message event that has been constructed. See <code>Usage</code> section for more details. </dd></dl>
<dl class="user"><dt><b></b></dt><dd>Note that publishing events containing multiple messages may be more efficient than events limited to a single message for applications that send large volume of small messages. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="usage"></a> <a class="anchor" id="description.usage"></a> <a class="anchor" id="3.1"></a> </dd></dl>
<dl class="user"><dt><b>Usage: </b></dt><dd><ul>
<li>
An instance of <a class="el" href="classbmqa_1_1MessageEventBuilder.html">bmqa::MessageEventBuilder</a> (the builder) can be used to create multiple <a class="el" href="classbmqa_1_1MessageEvent.html">bmqa::MessageEvent</a>'s, as long as the instance is reset in between. This reset is preferably to do right after sending the event to guarantee that all user resources bound to the <a class="el" href="classbmqa_1_1MessageEvent.html">bmqa::MessageEvent</a> (e.g. CorrelationIds with user's shared_ptr) are kept no longer than expected (e.g. until related ACK event is received). The recommended approach is to create one instance of the builder and use that throughout the lifetime of the task (if the task is multi-threaded, an instance per thread must be created and maintained). See usage example #1 for an illustration.  </li>
<li>
The lifetime of an instance of the builder is bound by the <a class="el" href="classbmqa_1_1Session.html">bmqa::Session</a> from which it was created. In other words, <a class="el" href="classbmqa_1_1Session.html">bmqa::Session</a> instance must outlive the builder instance.  </li>
<li>
If it is desired to post the same <a class="el" href="classbmqa_1_1Message.html">bmqa::Message</a> to different queues, <code>packMessage</code> can be called multiple times in a row with different queue IDs. The builder will append the previously packed message with the new queue ID to the underlying message event. Note that after calling <code>packMessage</code>, the message keeps all the attributes (payload, properties, etc) that were previously set (except for the <code>correlationId</code> which must be set explicitly for each individual message). If desired, any attribute can be tweaked before being packing the message again. Refer to usage example #2 for an illustration.  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="example_1_-_basic_usage"></a> <a class="anchor" id="description.example_1_-_basic_usage"></a> <a class="anchor" id="3.2"></a> </dd></dl>
<dl class="user"><dt><b>Example 1 - Basic Usage: </b></dt><dd><div class="fragment"><pre class="fragment">   <span class="comment">// Note that error handling is omitted below for the sake of brevity</span>

   <a class="code" href="classbmqa_1_1Session.html">bmqa::Session</a> session;
       <span class="comment">// Session start up logic omitted for brevity.</span>

   <span class="comment">// Obtain a valid instance of message properties.</span>
   bmqt::MessageProperties properties;
   session.<a class="code" href="classbmqa_1_1Session.html#af92a8ab7524dc908ece5da97744a22f3">loadMessageProperties</a>(&amp;properties);

   <span class="comment">// Set common properties that will be applicable to all messages sent by</span>
   <span class="comment">// this application.</span>
   <span class="keywordtype">int</span> rc = properties.setPropertyAsChar(
                                   <span class="stringliteral">&quot;encoding&quot;</span>,
                                   static_cast&lt;char&gt;(MyEncodingEnum::e_BER));

   rc = properties.setPropertyAsString(<span class="stringliteral">&quot;producerId&quot;</span>, <span class="stringliteral">&quot;MyUniqueId&quot;</span>);

   <span class="comment">// Obtain a valid instance of message event builder.</span>
   <a class="code" href="classbmqa_1_1MessageEventBuilder.html">bmqa::MessageEventBuilder</a> builder;
   session.<a class="code" href="classbmqa_1_1Session.html#a898eeb0dd7a3407bb1a2788ae8ecb7ff">loadMessageEventBuilder</a>(&amp;builder);

   <span class="comment">// Create and post a message event containing 1 message.  Associate</span>
   <span class="comment">// properties with this message.</span>
   <a class="code" href="classbmqa_1_1Message.html">bmqa::Message</a>&amp; msg = builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a33d687a643555d8d42ae476c0ad70eaf">startMessage</a>();

   msg.<a class="code" href="classbmqa_1_1Message.html#a13966aa7376c58c8570cf64182ca8f9c">setCorrelationId</a>(myCorrelationId);

   <span class="comment">// Set payload (where &#39;myPayload&#39; is of type &#39;bdlbb::Blob&#39;)</span>
   msg.<a class="code" href="classbmqa_1_1Message.html#a979f3d17c493015eb01928c77ec328d4">setDataRef</a>(&amp;myPayload);

   <span class="comment">// Set current timestamp as one of the properties.</span>
   rc = properties.setPropertyAsInt64(
                <span class="stringliteral">&quot;timestamp&quot;</span>,
                bdlt::EpochUtil::convertToTimeT64(bdlt::CurrentTime::now()));

   <span class="comment">// Set properties.</span>
   msg.<a class="code" href="classbmqa_1_1Message.html#a677a565424cbf6d9fe63c46b29c75fbe">setPropertiesRef</a>(&amp;properties);

   <span class="comment">// Pack the message.</span>
   rc = builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a101f3eea6233a4ff2b78b6b8072e3c50">packMessage</a>(myQueueId);

   <span class="comment">// Post message event</span>
   rc = session.<a class="code" href="classbmqa_1_1Session.html#a6e1d0349415ed25dafc141ad6d68c7e7">post</a>(builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a4998ec39691c9f90d639b554d681a782">messageEvent</a>());


   <span class="comment">// Create and post another message event containing 1 message.</span>

   <span class="comment">// bmqa::MessageEventBuilder must be reset before reuse.</span>
   builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#adc6901ca79289b4d7b71547ed1e66342">reset</a>();

   <span class="comment">// Start a new message.</span>
   <a class="code" href="classbmqa_1_1Message.html">bmqa::Message</a>&amp; msg = builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a33d687a643555d8d42ae476c0ad70eaf">startMessage</a>();

   msg.<a class="code" href="classbmqa_1_1Message.html#a13966aa7376c58c8570cf64182ca8f9c">setCorrelationId</a>(myAnotherCorrelationId);
   msg.<a class="code" href="classbmqa_1_1Message.html#a979f3d17c493015eb01928c77ec328d4">setDataRef</a>(&amp;myAnotherPayload);

   <span class="comment">// It&#39;s okay (and recommended) to use same properties instance.</span>
   rc = properties.setPropertyAsInt64(
                <span class="stringliteral">&quot;timestamp&quot;</span>,
                bdlt::EpochUtil::convertToTimeT64(bdlt::CurrentTime::now()));

   msg.<a class="code" href="classbmqa_1_1Message.html#a677a565424cbf6d9fe63c46b29c75fbe">setPropertiesRef</a>(&amp;properties);
   rc = builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a101f3eea6233a4ff2b78b6b8072e3c50">packMessage</a>(myAnotherQueueId);

   <span class="comment">// Post second message event</span>
   rc = session.<a class="code" href="classbmqa_1_1Session.html#a6e1d0349415ed25dafc141ad6d68c7e7">post</a>(builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a4998ec39691c9f90d639b554d681a782">messageEvent</a>());

   <span class="comment">// Reset the builder to free resources earlier.</span>
   builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#adc6901ca79289b4d7b71547ed1e66342">reset</a>();
</pre></div> </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="example_2_-_packing_multiple_messages_in_a_message_event"></a> <a class="anchor" id="description.example_2_-_packing_multiple_messages_in_a_message_event"></a> <a class="anchor" id="3.3"></a> </dd></dl>
<dl class="user"><dt><b>Example 2 - Packing multiple messages in a message event: </b></dt><dd><div class="fragment"><pre class="fragment">   <span class="comment">// Note that error handling is omitted below for the sake of brevity</span>

   <a class="code" href="classbmqa_1_1Session.html">bmqa::Session</a> session;
   <span class="comment">// Session start up logic omitted for brevity.</span>

   <span class="comment">// Obtain a valid instance of message properties.</span>
   bmqt::MessageProperties properties;
   session.<a class="code" href="classbmqa_1_1Session.html#af92a8ab7524dc908ece5da97744a22f3">loadMessageProperties</a>(&amp;properties);

   <span class="comment">// Set common properties that will be applicable to all messages sent by</span>
   <span class="comment">// this application.</span>
   <span class="keywordtype">int</span> rc = properties.setPropertyAsChar(
                                   <span class="stringliteral">&quot;encoding&quot;</span>,
                                   static_cast&lt;char&gt;(MyEncodingEnum::e_BER));

   rc = properties.setPropertyAsString(<span class="stringliteral">&quot;producerId&quot;</span>, <span class="stringliteral">&quot;MyUniqueId&quot;</span>);

   <span class="comment">// Obtain a valid instance of message event builder.</span>
   <a class="code" href="classbmqa_1_1MessageEventBuilder.html">bmqa::MessageEventBuilder</a> builder;
   session.<a class="code" href="classbmqa_1_1Session.html#a898eeb0dd7a3407bb1a2788ae8ecb7ff">loadMessageEventBuilder</a>(&amp;builder);

   <span class="comment">// Create and post a message event containing 4 messages.</span>
   <a class="code" href="classbmqa_1_1Message.html">bmqa::Message</a>&amp; msg = builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a33d687a643555d8d42ae476c0ad70eaf">startMessage</a>();

   <span class="comment">// Pack message #1</span>
   msg.<a class="code" href="classbmqa_1_1Message.html#a13966aa7376c58c8570cf64182ca8f9c">setCorrelationId</a>(correlationId1);
   msg.<a class="code" href="classbmqa_1_1Message.html#a979f3d17c493015eb01928c77ec328d4">setDataRef</a>(&amp;payload1);  <span class="comment">// where &#39;payload1&#39; is of type &#39;bdlbb::Blob&#39;</span>

   <span class="comment">// Set current timestamp as one of the properties.</span>
   <span class="keywordtype">int</span> rc = properties.setPropertyAsInt64(
                <span class="stringliteral">&quot;timestamp&quot;</span>,
                bdlt::EpochUtil::convertToTimeT64(bdlt::CurrentTime::now()));

   <span class="comment">// Pack the message.</span>
   rc = builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a101f3eea6233a4ff2b78b6b8072e3c50">packMessage</a>(queueId1);

   <span class="comment">// Pack message #2</span>
   <span class="comment">// We want to send message #1 to another queue.  In order to do so, we</span>
   <span class="comment">// just update the correlation ID of message #1.  There is no need to set</span>
   <span class="comment">// the payload or properties again.  Because &#39;payload1&#39; and &#39;properties&#39;</span>
   <span class="comment">// objects are being reused for the second message, they should not be</span>
   <span class="comment">// destroyed before packing the second message.</span>

   msg.<a class="code" href="classbmqa_1_1Message.html#a13966aa7376c58c8570cf64182ca8f9c">setCorrelationId</a>(correlationId2);

   <span class="comment">// Also note that the &quot;timestamp&quot; property for the second message will be</span>
   <span class="comment">// updated for this message.  There is no need to invoke</span>
   <span class="comment">// &#39;setPropertiesRef&#39; on the message though.</span>
   rc = properties.setPropertyAsInt64(
                <span class="stringliteral">&quot;timestamp&quot;</span>,
                bdlt::EpochUtil::convertToTimeT64(bdlt::CurrentTime::now()));

   rc = builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a101f3eea6233a4ff2b78b6b8072e3c50">packMessage</a>(queueId2);

   <span class="comment">// &#39;payload1&#39; can be safely destroyed at this point if it will not be</span>
   <span class="comment">// reused again for another message.</span>

   <span class="comment">// Pack message #3</span>
   <span class="comment">// Message #3 has a different payload, no properties and destined to</span>
   <span class="comment">// &#39;queueId1&#39;.</span>
   msg.<a class="code" href="classbmqa_1_1Message.html#a13966aa7376c58c8570cf64182ca8f9c">setCorrelationId</a>(correlationId3);
   msg.<a class="code" href="classbmqa_1_1Message.html#a979f3d17c493015eb01928c77ec328d4">setDataRef</a>(&amp;payload2);  <span class="comment">// where &#39;payload2&#39; is of type &#39;bdlbb::Blob&#39;</span>

   <span class="comment">// We need to explicitly clear out the associated properties.</span>
   msg.clearProperties();

   rc = builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a101f3eea6233a4ff2b78b6b8072e3c50">packMessage</a>(queueId1);

   <span class="comment">// Pack message #4</span>
   <span class="comment">// Message #4 has different payload and destined to &#39;queueId3&#39;.</span>
   msg.<a class="code" href="classbmqa_1_1Message.html#a13966aa7376c58c8570cf64182ca8f9c">setCorrelationId</a>(correlationId4);
   msg.<a class="code" href="classbmqa_1_1Message.html#a979f3d17c493015eb01928c77ec328d4">setDataRef</a>(&amp;payload3);  <span class="comment">// where &#39;payload3&#39; is of type &#39;bdlbb::Blob&#39;</span>

   <span class="comment">// Update &quot;timestamp&quot; property.</span>
   rc = properties.setPropertyAsInt64(
                <span class="stringliteral">&quot;timestamp&quot;</span>,
                bdlt::EpochUtil::convertToTimeT64(bdlt::CurrentTime::now()));

   <span class="comment">// Need to associate properties with the message, since they were cleared</span>
   <span class="comment">// out while packing message #3 above.</span>
   msg.<a class="code" href="classbmqa_1_1Message.html#a677a565424cbf6d9fe63c46b29c75fbe">setPropertiesRef</a>(&amp;properties);

   rc = builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a101f3eea6233a4ff2b78b6b8072e3c50">packMessage</a>(queueId3);

   <span class="comment">// Post second message event</span>
   rc = session.<a class="code" href="classbmqa_1_1Session.html#a6e1d0349415ed25dafc141ad6d68c7e7">post</a>(builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a4998ec39691c9f90d639b554d681a782">messageEvent</a>());

   <span class="comment">// Reset the builder to free resources earlier.</span>
   builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#adc6901ca79289b4d7b71547ed1e66342">reset</a>();
</pre></div> </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="thread_safety"></a> <a class="anchor" id="description.thread_safety"></a> <a class="anchor" id="3.4"></a> </dd></dl>
<dl class="user"><dt><b>Thread Safety: </b></dt><dd>This component is <em>NOT</em> thread safe. </dd></dl>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Thu Jun 15 2023 11:58:51 by&nbsp;
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.1 </small></address>
</body>
</html>
